<!DOCTYPE HTML>
<html>
<head>
<title>BOOMR utility functions</title>
<meta http-equiv="Content-type" content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="../boomerang-docs.css">
</head>
<body>
<span style="float:right;"><a href="../">All Docs</a> | <a href="index.html">Index</a></span>
<h1>BOOMR utility functions</h1>
<p>
All boomerang utility functions are under the <code>BOOMR.utils</code> namespace.
To access any of the following, dereference the BOOMR.utils object.  eg: use <code>BOOMR.utils.getCookie()</code>
to call the <code>getCookie()</code> method.
</p>

<h2 id="methods">Methods</h2>

<dl class="api">

<dt>getCookie(sName)</dt>
<dd>
<p>
Gets the value of the cookie identified by <code>sName</code>.
</p>
<h3>Returns</h3>
<ul>
<li>A string containing the cookie identified by <code>sName</code>.  This may be the empty string.</li>
<li><code>null</code> if the cookie wasn't found or if <code>sName</code> was empty.</li>
</ul>
</dd>

<dt>setCookie(sName, oSubCookies, nMaxAge, sPath, sDomain, bSecure)</dt>
<dd>
<p>
Sets the cookie named <code>sName</code> to the serialized value of <code>oSubCookies</code>.
</p>
<h3>Parameters:</h3>
<dl>

<dt>sName</dt>
<dd>The name of the cookie</dd>

<dt>oSubCookies</dt>
<dd>key/value pairs to write into the cookie.  These will be serialized as an &amp; separated
list of URL encoded key=value pairs.</dd>

<dt>nMaxAge</dt>
<dd>Lifetime in seconds of the cookie.  Set this to 0 to create a session cookie that expires when the browser
is closed.  If not set, defaults to 0.</dd>

<dt>sPath</dt>
<dd>The HTTP path that the cookie should be valid for.  The cookie will be sent to all URLs on this domain that
fall below sPath.  If not set, defaults to the path of the current document.  Unless you're on a server where
multiple users share the same domain, you probably want to set this to /</dd>

<dt>sDomain</dt>
<dd>The HTTP domain that the cookie should be vali for.  The cookie will be sent to all URLs that are subdomains
of this domain.  If not set, defaults to the current document's domain.  If set to <code>null</code>, it will
use the value of <code>site_domain</code> that was configured during the call to <a href="BOOMR.html#init">BOOMR.init()</a>.
You probably want to set this to <code>null</code>.
</dd>

<dt>bSecure</dt>
<dd>If set to true, then this cookie is only sent to HTTPS URLs.  If set to false (or not set), this cookie is sent to all
URLs that match the above rules.  Unless your site is completely SSL based, you can leave this unset.</dd>
</dl>

<p>
Note that the entire cookie name and value needs to be less than 4000 characters.
</p>

<h3>Example:</h3>
<p>
The <code>BOOMR.plugins.RT</code> plugin uses this function like this:
</p>
<pre>
if(!BOOMR.utils.setCookie(
			impl.cookie,
			{ s: t_start, r: url },
			impl.cookie_exp,
			"/",
			null
		)) {
	BOOMR.error("cannot set start cookie", "rt");
	return this;
}
</pre>

<h3>Returns</h3>
<ul>
<li><code>true</code> if the cookie was set successfully</li>
<li><code>false</code> if the cookie was not set successfully</li>
</ul>
</dd>

<dt>getSubCookies(sCookie)</dt>
<dd>
<p>
Parse a cookie string returned by <code>getCookie()</code> and split it into its constituent subcookies.
</p>
<h3>Example:</h3>
<p>
The <code>BOOMR.plugins.BW</code> plugin calls this function like this:
</p>
<pre>
var cookies = BOOMR.utils.getSubCookies(BOOMR.utils.getCookie(impl.cookie));
</pre>
<h3>Returns</h3>
<ul>
<li>On success, an object of key/value pairs of all sub cookies.  Note that some subcookies may have empty values.</li>
<li><code>null</code> if <code>sCookie</code> was not set or did not contain valid subcookies.</li>
</ul>
</dd>

<dt>removeCookie(sName)</dt>
<dd>
<p>
Removes the cookie identified by <code>sName</code> by nullifying its value, and making it a session cookie.
</p>
<h3>Returns</h3>
<p>
Nothing useful.
</p>
</dd>

<dt>pluginConfig(oImpl, oConfig, sName, aProperties)</dt>
<dd>
<p>
Convenience method that plugins can call to configure themselves with the config object passed in to their <code>init()</code>
method.
</p>
<h3>Parameters:</h3>
<dl>
<dt>oImpl</dt>
<dd>The plugin's impl object within which it stores all its configuration and private properties</dd>

<dt>oConfig</dt>
<dd>The config object passed in to the plugin's <code>init()</code> method.</dd>

<dt>sName</dt>
<dd>The plugin's name in the <code>BOOMR.plugins</code> object.</dd>

<dt>aProperties</dt>
<dd>An array containing a list of all configurable properties that this plugin has.</dd>
</dl>

<h3>Example:</h3>
<p>
The <code>BOOMR.plugins.RT</code> plugin uses this method like this:
</p>
<pre>
BOOMR.utils.pluginConfig(impl, config, "RT", ["cookie", "cookie_exp", "strict_referrer"]);
</pre>

<h3>Returns</h3>
<ul>
<li><code>true</code> if at least one property was set.</li>
<li><code>false</code> if no properties were set or if the oConfig object was not set.</li>
</ul>
</dd>

</dl>

<p class="perma-link">
The latest code and docs is available on <a href="http://github.com/lognormal/boomerang/">github.com/lognormal/boomerang</a>
</p>

</body>
</html>
<!--
    Copyright (c) 2011, Yahoo! Inc.  All rights reserved.
    Copyrights licensed under the BSD License. See the accompanying LICENSE.txt file for terms.
-->
